home *** CD-ROM | disk | FTP | other *** search
/ Amiga Games: Greatest Hits 1996 / Amiga Games: Greatest Hits 1996.iso / archive / userbox / publicdomain / xfd.lha / xfd / Developper / autodoc / xfdsub.doc < prev   
Text File  |  1996-08-03  |  10KB  |  303 lines
  1. TABLE OF CONTENTS
  2.  
  3. xfdForeman/--Overview--
  4. xfdSlave/--Overview--
  5. xfdSlave/DecrunchBufferXYZ
  6. xfdSlave/DecrunchSegmentXYZ
  7. xfdSlave/RecogBufferXYZ
  8. xfdSlave/RecogSegmentXYZ
  9. xfdSlave/ScanDataXYZ
  10. xfdSlave/VerifyDataXYZ
  11.  
  12. xfdForeman/--Overview--                               xfdForeman/--Overview--
  13.  
  14. The xfdForeman structure is just some kind of header for external slaves.
  15. It protects the slaves from being executed accidentally by having a small
  16. piece of code (moveq #-1,d0 : rts) in the first 4 bytes.
  17. The master can identify a valid bunch of external slaves by checking the
  18. first few bytes of the file for the foreman identification.
  19. Finally, a foreman holds the pointer to a linked list of slaves and thus
  20. enables the master to work with these slaves.
  21.  
  22. xfdSlave/--Overview--                                   xfdSlave/--Overview--
  23.  
  24. The xfdSlave structure is the heart of the whole library system. Each slave
  25. enables the master to recognize and decrunch packed files. Additionally,
  26. slaves of the type XFDPFB_RELOC can recognize and decrunch segments.
  27. Slaves with XFDPFB_DATA flag set contain routines for data scan and data
  28. verification.
  29.  
  30. Therefore each slave contains 4 routines that are called from the master.
  31. Pointers to these are stored in xfds_RecogBuffer and xfds_DecrunchBuffer.
  32. XFDPFB_RELOC slaves have xfds_RecogSegment and xfds_DecrunchSegment
  33. initialized, XFDPFB_DATA slaves use xfds_ScanData and xfds_VerifyData.
  34.  
  35. All routines have one thing in common: the CPU registers D0/D1/A0/A1 are
  36. so-called scratch registers, they may change during execution, all other
  37. registers must remain unchanged. CPU register A6 holds a pointer to the
  38. xfdMasterBase structure. See chapters below for a description of the slave
  39. routines.
  40.  
  41. ALL SLAVE ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC MEMORY
  42. AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT THE
  43. ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME!
  44.  
  45. The name of the packer that is supported by the slave and the flags that
  46. describe the packer are stored in xfds_PackerName and xfds_PackerFlags.
  47.  
  48. (V36) Internal slaves all have an unique ID value stored in xfds_SlaveID.
  49. This field should be set to NULL for external slaves.
  50.  
  51. (V36) If you have written a slave that should replace an internal one
  52. because it's faster or otherwise enhanced, simply put the ID of the slave
  53. to be replaced in xfds_ReplaceID. The old slave will then be taken out of
  54. the list of used slaves. Otherwise, xfds_ReplaceID must be NULL.
  55.  
  56. (V36) xfdRecogBuffer() usually only requires a quite small part of a file
  57. to recognize it properly. To avoid reading the whole file for recognition
  58. purposes, you may set xfds_MinBufferSize to the minimum amount of bytes
  59. that is required to recognize the crunched file correctly.
  60. Note that xfdRecogBuffer() uses this value internally to decide whether
  61. a file might be crunched with a packer or not, so you don't have to do
  62. an extra size comparison in your xfds_RecogBuffer function any more.
  63. For packer headers with non-constant sizes, simply set xfds_MinBufferSize
  64. to a value that will ensure correct recognition of all possible files.
  65.  
  66. Whenever you intend to use features of the xfdmaster.library in your slaves
  67. that are marked (V34) or higher, make sure to set xfds_MasterVersion to
  68. the desired version number, otherwise an old library version might crash
  69. while using the new slave.
  70.  
  71. xfdSlave/DecrunchBufferXYZ                         xfdSlave/DecrunchBufferXYZ
  72.  
  73.    NAME
  74.     DecrunchBufferXYZ -- Decrunch file from buffer to buffer.
  75.  
  76.    SYNOPSIS
  77.     result = DecrunchBufferXYZ(bufferinfo)
  78.       D0                           A0
  79.  
  80.     BOOL DecrunchBufferXYZ(struct xfdBufferInfo *);
  81.  
  82.    FUNCTION
  83.     The typical steps of such a routine are:
  84.     - Get length of decrunched file (exactly or a bit too much).
  85.     - Allocate memory (with memtype from xfdbi_TargetBufMemType).
  86.     - Decrunch file from xfdbi_SourceBuffer to xfdbi_TargetBuffer.
  87.     - Initialize all necessary parts of the xfdBufferInfo structure.
  88.     - Set xfdbi_Error if an error occurs.
  89.  
  90.    INPUTS
  91.     bufferinfo - A valid xfdBufferInfo structure that successfully went
  92.                  through a call to xfdRecogBuffer().
  93.  
  94.    RESULT
  95.     result - TRUE if decrunching succeeded, FALSE if something went wrong.
  96.  
  97.    NOTE
  98.     You have to initialize xfds_DecrunchBuffer with a pointer to your
  99.     DecrunchBufferXYZ routine.
  100.  
  101.    SEE ALSO
  102.     Example sourcecodes.
  103.  
  104. xfdSlave/DecrunchSegmentXYZ                       xfdSlave/DecrunchSegmentXYZ
  105.  
  106.    NAME
  107.     DecrunchSegmentXYZ -- Decrunch segment list.
  108.  
  109.    SYNOPSIS
  110.     result = DecrunchSegmentXYZ(segmentinfo)
  111.       D0                             A0
  112.  
  113.     BOOL DecrunchSegmentXYZ(struct xfdSegmentInfo *);
  114.  
  115.    FUNCTION
  116.     There are two possibilities how to decrunch a segment list. The
  117.     first one works like this:
  118.     - Modify decrunch header to make it return to the caller.
  119.     - Call decrunch header.
  120.     - dos.library/UnloadSeg() whole seglist and clear xfdsi_SegList
  121.       if an error occurs and the seglist has already been altered
  122.       in any way.
  123.     - Otherwise only release segments that are no longer necessary.
  124.     - Store BPTR to first hunk of decrunched segment list in
  125.       xfdsi_SegList.
  126.     - Set xfdsi_Error if an error occurs.
  127.  
  128.     The second possibility works the same way as the first with
  129.     the difference that you don't jump to the original code, but you
  130.     include all necessary parts of it (decrunch routine, relocator)
  131.     in your own routine. The big advantage is that you can handle
  132.     error conditions much better because most of the standard decrunch
  133.     headers in executable files have problems with low memory etc.
  134.  
  135.     (V34) If the decruncher allows it, always support XFDPFB_RELMODE.
  136.     That way the caller can determine the type of memory the segments
  137.     should be placed in by initializing xfdsi_RelMode with XFDREL_#?.
  138.  
  139.     Many crunchers don't change the hunk structure of the crunched
  140.     data. If this is the case, you can simply call the decrunch code
  141.     in the segment list and then use xfdRelocate() (V34).
  142.  
  143.    INPUTS
  144.     segmentinfo - A valid xfdSegmentInfo structure that successfully went
  145.                   through a call to xfdRecogSegment().
  146.  
  147.    RESULT
  148.     result - TRUE if decrunching succeeded, FALSE if something went wrong.
  149.  
  150.    NOTE
  151.     You have to initialize xfds_DecrunchSegment with a pointer to your
  152.     DecrunchSegmentXYZ routine.
  153.  
  154.    SEE ALSO
  155.     Example sourcecodes.
  156.  
  157. xfdSlave/RecogBufferXYZ                               xfdSlave/RecogBufferXYZ
  158.  
  159.    NAME
  160.     RecogBufferXYZ -- Recognize crunched file in buffer.
  161.  
  162.    SYNOPSIS
  163.     result = RecogBufferXYZ(buffer, length)
  164.       D0                      A0      D0
  165.  
  166.     BOOL RecogBufferXYZ(APTR, ULONG);
  167.  
  168.    FUNCTION
  169.     This routine should examine the buffer for a crunched file.
  170.     First thing is to check if the size of the file allows it to
  171.     be crunched with the packer in question. After that, simply
  172.     do some compares to figure out if the file has been crunched
  173.     or not.
  174.  
  175.     (V36) You don't have to do any size comparisons if you set
  176.     xfds_MinBufferSize to the minimum amount of bytes that are
  177.     necessary for a file to be crunched with that packer.
  178.  
  179.    INPUTS
  180.     buffer - Pointer to a buffer that holds the crunched file.
  181.     length - Length of that buffer.
  182.  
  183.    RESULT
  184.     result - TRUE if packer has been recognized, else FALSE.
  185.  
  186.    NOTE
  187.     You have to initialize xfds_RecogBuffer with a pointer to your
  188.     RecogBufferXYZ routine.
  189.  
  190.    SEE ALSO
  191.     Example sourcecodes.
  192.  
  193. xfdSlave/RecogSegmentXYZ                             xfdSlave/RecogSegmentXYZ
  194.  
  195.    NAME
  196.     RecogSegmentXYZ -- Recognize crunched segment list.
  197.  
  198.    SYNOPSIS
  199.     result = RecogSegmentXYZ(seglist)
  200.       D0                       A0
  201.  
  202.     BOOL RecogSegmentXYZ(BPTR);
  203.  
  204.    FUNCTION
  205.     This routine should examine if a segment list is crunched.
  206.     You can check the whole segment list for correct lengths of hunks
  207.     and for contents of hunks if you like. There should be at least
  208.     3 comparations to determine the cruncher.
  209.  
  210.    INPUTS
  211.     seglist - BPTR to first segment.
  212.  
  213.    RESULT
  214.     result - TRUE if packer has been recognized, else FALSE.
  215.  
  216.    NOTE
  217.     You have to initialize xfds_RecogSegment with a pointer to your
  218.     RecogSegmentXYZ routine.
  219.  
  220.    SEE ALSO
  221.     Example sourcecodes.
  222.  
  223. xfdSlave/ScanDataXYZ                                     xfdSlave/ScanDataXYZ
  224.  
  225.    NAME
  226.     ScanDataXYZ -- Recognize crunched data in buffer.
  227.  
  228.    SYNOPSIS
  229.     result = ScanDataXYZ(buffer, length)
  230.       D0                   A0      D0
  231.  
  232.     BOOL ScanDataXYZ(APTR, ULONG);
  233.  
  234.    FUNCTION
  235.     This routine should only test for the usual data ID at exactly the
  236.     address given as buffer. The length is the amount of bytes until
  237.     the end of the whole buffer and is of minor use in this context.
  238.     You may use it if the ID is several bytes long to test if buffer
  239.     is already at its end.
  240.  
  241.    EXAMPLE
  242.     ScanDataS400    moveq    #0,d0
  243.             cmp.l    #'S400',(a0)    ;StoneCracker Data ID
  244.             bne.s    .Exit
  245.             moveq    #1,d0
  246.     .Exit        rts
  247.  
  248.    INPUTS
  249.     buffer - Pointer to a address to scan at.
  250.     length - Length of whole buffer.
  251.  
  252.    RESULT
  253.     result - TRUE if crunched data has been recognized, else FALSE.
  254.  
  255.    NOTE
  256.     You have to initialize xfds_ScanData with a pointer to your
  257.     ScanDataXYZ routine.
  258.  
  259. xfdSlave/VerifyDataXYZ                                 xfdSlave/VerifyDataXYZ
  260.  
  261.    NAME
  262.     VerifyDataXYZ -- Check crunched data and return length.
  263.  
  264.    SYNOPSIS
  265.     length = VerifyDataXYZ(buffer, length)
  266.       D0                     A0      D0
  267.  
  268.     ULONG VerifyDataXYZ(APTR, ULONG);
  269.  
  270.    FUNCTION
  271.     This routine is called after ScanDataXYZ and first has to check if
  272.     the data ID found while scanning is part of a valid data file or
  273.     just some piece of code etc.
  274.  
  275.     If it is a valid data file, it has to calculate the final length
  276.     of the data file starting at the ID until the end. This value will
  277.     then be used for the xfdScanNode structure.
  278.  
  279.    EXAMPLE
  280.     VerifyDataS400    moveq    #$c,d1
  281.             add.l    8(a0),d1    ;crlen
  282.             cmp.l    d0,d1        ;crlen > buflen ??
  283.             bgt.s    .Exit
  284.             move.l    4(a0),d0
  285.             sub.l    8(a0),d0    ;cr > uncr ??
  286.             bmi.s    .Exit
  287.             move.l    d1,d0
  288.             rts
  289.     .Exit        moveq    #0,d0
  290.             rts
  291.  
  292.    INPUTS
  293.     buffer - Pointer to start address of possible data file.
  294.     length - Length of whole buffer.
  295.  
  296.    RESULT
  297.     length - Final length of found data file, else NULL.
  298.  
  299.    NOTE
  300.     You have to initialize xfds_VerifyData with a pointer to your
  301.     VerifyDataXYZ routine.
  302.  
  303.